Alias

CscSignaturesSignHash

Description

Generates one or more digital signatures (i.e., an individual signature or a batch of signatures) from the hashes of the data to be signed, using the signing key corresponding to a given signature credential.

Request

To generate one or more signatures from the hashes of the data to be signed, the client application must send the following request to the TRIDENT:

POST /trustedx-resources/csc/v2/signatures/signHash

Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be /csc/v2/. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is /csc/v2 instead of /trustedx-resources/csc/v2. To determine if this is the case in your situation, check the "oauth2" property of the JSON object provided by the Obtain information on the CSC signature service operation.

Content-Type Header

Content-Type: application/json

Request Parameters

Name	Type	Usage	Description
`credentialID`	String	Required	Identifier of the signature credential associated with the signing key with which the signatures will be generated.
`SAD`	String	Conditionally Required	The access token with which the application demonstrates the user granted authorization for signing the data corresponding to the hashes specified in the `hashes` parameter with the key referred to in the `credentialID` parameter. This access token must have `credential` scope and be obtained in an Authorization Code Grant OAuth 2.0 authorization flow. It is unnecessary if one access token like this is in the HTTP Authorization header.
`hashes`	String Array	Required	List of hashes (encoded in base64) of the data to be signed. The number of hashes in the list must be equal to or less than the value of the `numSignatures` parameter used to obtain the authorization demonstrated by the token contained in the `SAD` parameter or in the `Authorization` header.
`hashAlgorithmOID`	Boolean	Conditionally Required	Identifier (OID) of the algorithm with which the hashes were generated based on which the signatures will be generated. This parameter is only necessary when the algorithm is not implicit in the algorithm specified in the `signAlgo` parameter (i.e. when this algorithm is RSA encryption).
`signAlgo`	String	Required	Identifier (OID) of the algorithm that must be used to generate the signatures. It must be one of the following values, provided that the signature credential allows it (see the `keyAlgo` parameter of the response of the Obtain a signature credential of a user operation) "`1.2.840.113549.1.1.1`": RSA encryption "`1.2.840.113549.1.1.11`": sha256WithRSAEncryption "`1.2.840.113549.1.1.12`": sha384WithRSAEncryption "`1.2.840.113549.1.1.13`": sha512WithRSAEncryption "`1.2.840.10045.4.3.2`": sha 256WithECDSA " `1.2.840.10045.4.3.3`": sha384 WithECDSA " `1.2.840.10045.4.3.4`": sha512 WithECDSA

Authorization

This operation can be authorized by including one or two access tokens in the request.

Authorization with one access token

The request must contain a bearer access token with the credential scope in the Authorization header. This token can only be obtained via an OAuth 2.0 Authorization Code Grant flow and must be bound to the signing key to be used (through the credentialID parameter) and to the data to be signed (through the hashes parameter). In addition, the SAD parameter must not be used.

Authorization with two access tokens

The request must contain two OAuth 2.0 access tokens:

An access token with the service scope in the Authorization header. As a rule, this token can be obtained as much via an OAuth 2.0 Authorization Code Grant flow as an OAuth 2.0 Client Credentials Grant flow. Find out from the TRIDENT administrator if this is the case in your situation or if the access token can only be obtained via a particular type of OAuth 2.0 flow.
An access token with the credential scope as the SAD parameter's value. This token can only be obtained via an OAuth 2.0 Authorization Code Grant flow and must be bound to the signing key to be used (through the credentialID parameter) and to the data to be signed (through the hashes parameter).

In both cases, the token in the header must be put as explained in RFC 6750. I.e., as follows:

Authorization: Bearer <token>

Response

Status-Line

If the digital signatures are successfully generated, the HTTP response contains the following Status-Line:

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object containing the digital signatures requested in the same order in which the hashes were provided in the request.

{
    "signatures": [{string}]
}

Property	Type	Description
`signatures`	String Array	List (batch) of digital signatures that were generated. The signatures are provided in the same order in which the hashes used for the generation were given in the request. Each signature is a PKCS #1 encoded in base64.

Error Management

If the request does not contain the Authorization: Bearer header, the TRIDENT returns an HTTP response with the 401 Unauthorized Status Code.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the Content-Type: application/json;charset=utf-8 header and a JSON object in the body with the following properties:

error: Error code.
error_description: Additional description of the error. Not required.

Error case	Status Code (HTTP)	error	error_description
The `SAD` parameter was not included in the request or its value is not a string	400 Bad Request	`invalid_request`	`invalidParameter`
The `SAD` parameter of the request is invalid	400 Bad Request	`invalid_request`	`invalidSAD`
The `credentialID` parameter was not included in the request, or its value is not a string.	400 Bad Request	`invalid_request`	`invalidParameter`
The `credentialID` parameter of the request is invalid	400 Bad Request	`invalid_request`	`invalidCredentialID`
The `hashes` parameter was not included in the request, or its value is not a string array.	400 Bad Request	`invalid_request`	`invalidParameter`
The value of the `hashes` parameter is an empty array (it does not contain any element).	400 Bad Request	`invalid_request`	`invalidParameter`
The base64 encoding of one of the hashes in the list of hashes of the `hashes` parameter of the request is invalid.	400 Bad Request	`JsonMappingException`
One or more of the hashes in the list of hashes of the `hashes` parameter is not authorized by the SAD token included in the `SAD` parameter of the request.	400 Bad Request	`invalid_request`	`invalidSAD`
The `signAlgo` parameter was not included in the request, or its value is not a string.	400 Bad Request	`invalid_request`	`invalidParameter`
The `hashAlgorithmOID` parameter was not included in the request, or its value is not a string, and the value of the `signAlgo` parameter of the request is “`1.2.840.113549.1.1.1`” (RSA encryption).	400 Bad Request	`invalid_request`	`invalidDigestAlgorithm`
The `hashAlgorithmOID` parameter of the request is invalid.	400 Bad Request	`invalid_request`	`invalidDigestAlgorithm`
The `signAlgo` parameter of the request is invalid.	400 Bad Request	`invalid_request`	`invalidSignatureAlgorithm`
The length of one of the hashes in the list of hashes of the `hashes` parameter is wrong.	400 Bad Request	`invalid_request`	`invalidHashLength`
The SAD token included in the `SAD` parameter of the request is expired.	400 Bad Request	`invalid_request`	`invalidSAD`
The `credentialID` parameter of the request corresponds to an expired signature credential.	400 Bad Request	`invalid_request`	`expiredCredential`
The `credentialID` parameter of the request corresponds to a disabled signature credential	403 Forbidden	`DisabledSignIdentityException`

Example

Request

The signature application requests the generation of the digital signature of the data corresponding to the "TMkLHG9F5EE1X3YxkimehiuRDV9RcepZnKZ1dUAlHiQ=" hash (encoded in base64) with the signing key that corresponds to the credential identified by "GX0112348". To do this, it sends the following request to the TRIDENT:

POST /trustedx-resources/csc/v2/signatures/signHash HTTP/1.1
Host: rse.corporation.com
 
Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597
Content-Type: application/json
 
{    
    "credentialID": "GX0112348",
    "hashes": ["TMkLHG9F5EE1X3YxkimehiuRDV9RcepZnKZ1dUAlHiQ="],
    "signAlgo": "1.2.840.113549.1.1.11"
}

Response

The TRIDENT generates the digital signature requested and responds to the signature application with the following message:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "signatures":["KegbGQAqNXDR3cTjQ8...EGo7zY8DrCFI="]
}